Intro

A gt table can contain a few useful parts for conveying additional information. These include a header (with a titles and subtitle), a footer (with footnotes and source notes), and additional areas for labels (row group labels, column spanner labels, the stubhead label). We can modify the look of table parts more generally with tab_options() and perform styling on targeted table locations with tab_style().

Functions in this module

  • tab_header()
  • tab_stubhead()
  • tab_spanner()
  • tab_row_group()
  • tab_source_note()
  • tab_footnote()
  • tab_style()
  • tab_options()

Some of the helper functions (from {dplyr}) for selecting columns and rows:

  • contains()
  • matches()
  • starts_with()
  • ends_with()
  • everything()

Helpers for transforming text:

  • md()
  • html()

Helpers for targeting locations (for tab_footnote() and tab_style()):

  • cells_title()
  • cells_stubhead()
  • cells_column_spanners()
  • cells_column_labels()
  • cells_row_groups()
  • cells_stub()
  • cells_body()
  • cells_summary()
  • cells_grand_summary()

Helpers for defining styles (only for tab_style()):

  • cell_text()
  • cell_fill()
  • cell_borders()

tab_header(): Add a table header

tab_header(
  data,
  title,
  subtitle = NULL,
  preheader = NULL
)

We can add a table header to the gt table with a title and optionally a subtitle. A table header is an optional table part that is positioned above the column labels:

We have the flexibility to use Markdown or HTML formatting for the header’s title and subtitle (with md() or html()).

EXAMPLE

Use gtcars to create a gt table; add a header part to contain a title and subtitle.

#Show this with and without the md() function
gtcars |>
  dplyr::select(mfr, model, msrp) |>
  dplyr::slice(1:5) |>
  gt() |>
  tab_header(
    title = md("Data listing from **gtcars**"),
    subtitle = html("<b><span style = 'color:#C6473E;'>gtcars</span></b> is an R dataset")
  )
Data listing from gtcars
gtcars is an R dataset
mfr model msrp
Ford GT 447000
Ferrari 458 Speciale 291744
Ferrari 458 Spider 263553
Ferrari 458 Italia 233509
Ferrari 488 GTB 245400

tab_stubhead(): Add label text to the stubhead

tab_stubhead(
  data,
  label
)

Add a label to the stubhead of a gt table. The stubhead is the lone element that is positioned left of the column labels, and above the stub:

We have the flexibility to use Markdown formatting for the stubhead label with md(). Furthermore, if the table is intended for HTML output, we can use HTML for the stubhead label (with html()).

EXAMPLE

Use gtcars to create a gt table. Add a stubhead label to describe what is in the stub.

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:5) |>
  gt(rowname_col = "model") |>
  tab_stubhead(label = "car")
car year hp trq
GT 2017 647 550
458 Speciale 2015 597 398
458 Spider 2015 562 398
458 Italia 2014 562 398
488 GTB 2016 661 561

tab_spanner(): Add a spanner column label

tab_spanner(
  data,
  label,
  columns = NULL,
  spanners = NULL,
  level = NULL,
  id = label,
  gather = TRUE,
  replace = FALSE
)

Set a spanner column label by mapping it to columns already in the table. This label is placed above one or more column labels, spanning the width of those columns and column labels:

With columns we can use column names in double quotes ("<column>"), in c() (c(<column>)), or, we can use the following tidyselect expressions:

  • contains(): contains a literal string
  • matches(): matches a regular expression
  • starts_with(): starts with a prefix
  • ends_with(): ends with a suffix
  • everything(): selects all columns
EXAMPLES

Let’s use the gtcars table, but cut it down to size first:

gtcars_small <- 
  gtcars |>
  dplyr::select(
    -mfr, -trim, bdy_style, drivetrain,
    -drivetrain, -trsmn, -ctry_origin
  ) |>
  dplyr::slice(1:8)

gtcars_small
## # A tibble: 8 × 10
##   model         year bdy_style      hp hp_rpm   trq trq_rpm mpg_c mpg_h   msrp
##   <chr>        <dbl> <chr>       <dbl>  <dbl> <dbl>   <dbl> <dbl> <dbl>  <dbl>
## 1 GT            2017 coupe         647   6250   550    5900    11    18 447000
## 2 458 Speciale  2015 coupe         597   9000   398    6000    13    17 291744
## 3 458 Spider    2015 convertible   562   9000   398    6000    13    17 263553
## 4 458 Italia    2014 coupe         562   9000   398    6000    13    17 233509
## 5 488 GTB       2016 coupe         661   8000   561    3000    15    22 245400
## 6 California    2015 convertible   553   7500   557    4750    16    23 198973
## 7 GTC4Lusso     2017 coupe         680   8250   514    5750    12    17 298000
## 8 FF            2015 coupe         652   8000   504    6000    11    16 295000

Let’s look at the table in gt so that we know where we are starting from.

gtcars_small |> gt(rowname_col = "model")
year bdy_style hp hp_rpm trq trq_rpm mpg_c mpg_h msrp
GT 2017 coupe 647 6250 550 5900 11 18 447000
458 Speciale 2015 coupe 597 9000 398 6000 13 17 291744
458 Spider 2015 convertible 562 9000 398 6000 13 17 263553
458 Italia 2014 coupe 562 9000 398 6000 13 17 233509
488 GTB 2016 coupe 661 8000 561 3000 15 22 245400
California 2015 convertible 553 7500 557 4750 16 23 198973
GTC4Lusso 2017 coupe 680 8250 514 5750 12 17 298000
FF 2015 coupe 652 8000 504 6000 11 16 295000

Use gtcars to create a gt table; Group several columns related to car performance under a spanner column with the label performance.

gtcars_small |>
  gt(rowname_col = "model") |>
  tab_spanner(
    label = "performance",
    columns = c(hp, hp_rpm, trq, trq_rpm, mpg_c, mpg_h)
  )
year bdy_style
performance
 msrp
hp hp_rpm trq trq_rpm mpg_c mpg_h
GT 2017 coupe 647 6250 550 5900 11 18 447000
458 Speciale 2015 coupe 597 9000 398 6000 13 17 291744
458 Spider 2015 convertible 562 9000 398 6000 13 17 263553
458 Italia 2014 coupe 562 9000 398 6000 13 17 233509
488 GTB 2016 coupe 661 8000 561 3000 15 22 245400
California 2015 convertible 553 7500 557 4750 16 23 198973
GTC4Lusso 2017 coupe 680 8250 514 5750 12 17 298000
FF 2015 coupe 652 8000 504 6000 11 16 295000

With a few tidyselect statements in c(), we can get the same columns.

gtcars_small |>
  gt(rowname_col = "model") |>
  tab_spanner(
    label = "performance",
    columns = c(starts_with("hp"), starts_with("trq"), starts_with("mpg"))
  )
year bdy_style
performance
 msrp
hp hp_rpm trq trq_rpm mpg_c mpg_h
GT 2017 coupe 647 6250 550 5900 11 18 447000
458 Speciale 2015 coupe 597 9000 398 6000 13 17 291744
458 Spider 2015 convertible 562 9000 398 6000 13 17 263553
458 Italia 2014 coupe 562 9000 398 6000 13 17 233509
488 GTB 2016 coupe 661 8000 561 3000 15 22 245400
California 2015 convertible 553 7500 557 4750 16 23 198973
GTC4Lusso 2017 coupe 680 8250 514 5750 12 17 298000
FF 2015 coupe 652 8000 504 6000 11 16 295000

If we relocate the "hp" column to the beginning (i.e., far left), the associated columns are gathered together.

#Note: You can have multiple tab spanners!

gtcars_small |>
  dplyr::select(hp, everything()) |> # hp column is relocated
  gt(rowname_col = "model") |>
    tab_spanner(
    label = "performance",
    columns = c(hp, hp_rpm, trq, trq_rpm, mpg_c, mpg_h)
  )
performance
 year bdy_style msrp
hp hp_rpm trq trq_rpm mpg_c mpg_h
GT 647 6250 550 5900 11 18 2017 coupe 447000
458 Speciale 597 9000 398 6000 13 17 2015 coupe 291744
458 Spider 562 9000 398 6000 13 17 2015 convertible 263553
458 Italia 562 9000 398 6000 13 17 2014 coupe 233509
488 GTB 661 8000 561 3000 15 22 2016 coupe 245400
California 553 7500 557 4750 16 23 2015 convertible 198973
GTC4Lusso 680 8250 514 5750 12 17 2017 coupe 298000
FF 652 8000 504 6000 11 16 2015 coupe 295000

tab_source_note(): Add a source note citation

tab_source_note(
  data,
  source_note
)

We can add a source note to the footer part of any gt table. A source note is useful for citing the data included in the table.

Several can be added, simply use multiple calls of tab_source_note() and they will be inserted in the order provided. We can use Markdown formatting for the note, or, if the table is intended for HTML output, we can include HTML formatting.

EXAMPLE

Use exibble to create a gt table. Add a source note to the table footer that cites the data source.

exibble |>
  gt() |>
  tab_source_note(
    source_note = md("The `exibble` dataset is available in the **gt** package.")
  )
num char fctr date time datetime currency row group
1.111e-01 apricot one 2015-01-15 13:35 2018-01-01 02:22 49.950 row_1 grp_a
2.222e+00 banana two 2015-02-15 14:40 2018-02-02 14:33 17.950 row_2 grp_a
3.333e+01 coconut three 2015-03-15 15:45 2018-03-03 03:44 1.390 row_3 grp_a
4.444e+02 durian four 2015-04-15 16:50 2018-04-04 15:55 65100.000 row_4 grp_a
5.550e+03 NA five 2015-05-15 17:55 2018-05-05 04:00 1325.810 row_5 grp_b
NA fig six 2015-06-15 NA 2018-06-06 16:11 13.255 row_6 grp_b
7.770e+05 grapefruit seven NA 19:10 2018-07-07 05:22 NA row_7 grp_b
8.880e+06 honeydew eight 2015-08-15 20:20 NA 0.440 row_8 grp_b
The exibble dataset is available in the gt package.

tab_footnote(): Add a table footnote

tab_footnote(
  data,
  footnote,
  locations = NULL,
  placement = c("auto", "right", "left")
)

The tab_footnote() function can make it a painless process to add a footnote to a gt table. There are two components to a footnote: (1) a footnote mark that is attached to the targeted cell text, and (2) the footnote text (that starts with the corresponding footnote mark) that is placed in the table’s footer area.

Each call of tab_footnote() will add a different note, and one or more cells can be targeted via the location helper (use in locations):

  • cells_title() - target the table title or subtitle
  • cells_stubhead() - target the table stubhead cell
  • cells_column_spanners() - target the column spanners
  • cells_column_labels() - target the column labels
  • cells_row_groups() - target row groups
  • cells_stub() - target cells in the table stub
  • cells_body() - target data cells in the table body
  • cells_summary() - target group summary cells
  • cells_grand_summary() - target cells in a grand summary

Additionally, we can enclose several cells_*() calls within a list() if we wish to link the footnote text to different types of locations (e.g., body cells, row group labels, the table title, etc.).

EXAMPLE

Use exibble to create a gt table and then add a footnote to the fctr column label explaining what the short form means (fctr = ‘factor’).

exibble |>
  gt() |>
  tab_footnote(
    footnote = "This is a factor column.",
    locations = cells_column_labels(columns = fctr)
  )
num char fctr1 date time datetime currency row group
1.111e-01 apricot one 2015-01-15 13:35 2018-01-01 02:22 49.950 row_1 grp_a
2.222e+00 banana two 2015-02-15 14:40 2018-02-02 14:33 17.950 row_2 grp_a
3.333e+01 coconut three 2015-03-15 15:45 2018-03-03 03:44 1.390 row_3 grp_a
4.444e+02 durian four 2015-04-15 16:50 2018-04-04 15:55 65100.000 row_4 grp_a
5.550e+03 NA five 2015-05-15 17:55 2018-05-05 04:00 1325.810 row_5 grp_b
NA fig six 2015-06-15 NA 2018-06-06 16:11 13.255 row_6 grp_b
7.770e+05 grapefruit seven NA 19:10 2018-07-07 05:22 NA row_7 grp_b
8.880e+06 honeydew eight 2015-08-15 20:20 NA 0.440 row_8 grp_b
1 This is a factor column.

tab_style(): Add custom styles to one or more cells

tab_style(
  data,
  style,
  locations
)

With the tab_style() function we can target specific cells and apply styles to them.

This is done with the help of the following functions:

  • cell_text()
  • cell_fill()
  • cell_borders()

For locations we use the cells_*() functions, just like in the tab_footnote() function. In the example below, we’ll take things a step further with the cells_body() function and use a conditional statement in rows to target cells based on data.

EXAMPLES

Change the font of all body cells in the exibble table to Times New Roman. By default, using cells_body() without any arguments means all table body cells are targeted.

exibble |>
  dplyr::select(num, currency) |>
  gt() |>
  tab_style(
    style = cell_text(font = "Times New Roman"),
    locations = cells_body()
  )
num currency
1.111e-01 49.950
2.222e+00 17.950
3.333e+01 1.390
4.444e+02 65100.000
5.550e+03 1325.810
NA 13.255
7.770e+05 NA
8.880e+06 0.440

Use a font from the Google Fonts service by using the google_font() function. Recommendations on some Google fonts can be found by using info_google_fonts().

exibble |>
  dplyr::select(num, currency) |>
  gt() |>
  fmt_currency(columns = currency, currency = "EUR") |>
  tab_style(
    style = cell_text(font = google_font("IBM Plex Sans"), weight = 500),
    locations = cells_body()
  )
num currency
1.111e-01 €49.95
2.222e+00 €17.95
3.333e+01 €1.39
4.444e+02 €65,100.00
5.550e+03 €1,325.81
NA €13.26
7.770e+05 NA
8.880e+06 €0.44

Use exibble to create a gt table. Add styles that are to be applied to data cells that satisfy a condition (using tab_style()).

exibble |>
  dplyr::select(num, currency) |>
  gt() |>
  fmt_number(
    columns = c(num, currency),
    decimals = 1
  ) |>
  tab_style(
    style = list(
      cell_fill(color = "cyan"),
      cell_text(weight = "bold")
      ),
    locations = cells_body(
      columns = num,
      rows = num >= 5000
    )
  ) |>
  tab_style(
    style = list(
      cell_fill(color = "#F9E3D6"),
      cell_text(style = "italic")
      ),
    locations = cells_body(
      columns = currency,
      rows = currency < 100
    )
  )
num currency
0.1 50.0
2.2 17.9
33.3 1.4
444.4 65,100.0
5,550.0 1,325.8
NA 13.3
777,000.0 NA
8,880,000.0 0.4

Use sp500 to create a gt table. Color entire rows of cells based on values in a particular column.

sp500 |>
  dplyr::filter(
    date >= "2015-12-01" &
    date <= "2015-12-15"
  ) |>
  dplyr::select(-c(adj_close, volume)) |>
  gt() |>
  tab_style(
    style = cell_fill(color = "lightgreen"),
    locations = cells_body(rows = close > open)
  ) |>
  tab_style(
    style = list(
      cell_fill(color = "tomato"),
      cell_text(color = "white")
      ),
    locations = cells_body(rows = open > close)
  )
date open high low close
2015-12-15 2025.55 2053.87 2025.55 2043.41
2015-12-14 2013.37 2022.92 1993.26 2021.94
2015-12-11 2047.27 2047.27 2008.80 2012.37
2015-12-10 2047.93 2067.65 2045.67 2052.23
2015-12-09 2061.17 2080.33 2036.53 2047.62
2015-12-08 2073.39 2073.85 2052.32 2063.59
2015-12-07 2090.42 2090.42 2066.78 2077.07
2015-12-04 2051.24 2093.84 2051.24 2091.69
2015-12-03 2080.71 2085.00 2042.35 2049.62
2015-12-02 2101.71 2104.27 2077.11 2079.51
2015-12-01 2082.93 2103.37 2082.93 2102.63

tab_options(): Modify the table output options

tab_options(
  data,
  container.width = NULL,
  container.height = NULL,
  container.overflow.x = NULL,
  container.overflow.y = NULL,
  table.width = NULL,
  table.layout = NULL,
  <many more options>
  page.header.height = NULL,
  page.footer.height = NULL,
  quarto.use_bootstrap = NULL,
  quarto.disable_processing = NULL
)

With tab_options() we can modify the global options for a gt table. These options are named by the components, the sub-components, and the element that can adjusted. This function has a very large set of arguments and many aspects of the table can be adjusted. Later on, we’ll take a look at some shortcuts to common options with the opt_*() functions.

EXAMPLES

Use exibble to create a gt table with all the main parts added; we can use this going forward to demo some tab_options().

tab_1 <- 
  exibble |>
  dplyr::select(
    -c(fctr, date, time, datetime)
  ) |>
  gt(
    rowname_col = "row",
    groupname_col = "group"
  ) |>
  tab_header(
    title = md("Data listing from **exibble**"),
    subtitle = md("`exibble` is an R dataset")
  ) |>
  fmt_number(columns = num) |>
  fmt_currency(columns = currency) |>
  tab_footnote(
    footnote = "Using commas for separators.",
    locations = cells_body(
      columns = num,
      rows = num > 1000
    )
  ) |>
  tab_footnote(
    footnote = "Using commas for separators.",
    locations = cells_body(
      columns = currency,
      rows = currency > 1000
    )
  ) |>
  tab_footnote(
    footnote = "Alphabetical fruit.",
    locations = cells_column_labels(columns = char)
  )

tab_1
Data listing from exibble
exibble is an R dataset
num char1 currency
grp_a
row_1 0.11 apricot $49.95
row_2 2.22 banana $17.95
row_3 33.33 coconut $1.39
row_4 444.40 durian 2 $65,100.00
grp_b
row_5 2 5,550.00 NA 2 $1,325.81
row_6 NA fig $13.26
row_7 2 777,000.00 grapefruit NA
row_8 2 8,880,000.00 honeydew $0.44
1 Alphabetical fruit.
2 Using commas for separators.

Modify the table width (with table.width) to 100% (which spans the entire content width area).

tab_1 |>
  tab_options(table.width = pct(100)) # pct() helper function used here
Data listing from exibble
exibble is an R dataset
num char1 currency
grp_a
row_1 0.11 apricot $49.95
row_2 2.22 banana $17.95
row_3 33.33 coconut $1.39
row_4 444.40 durian 2 $65,100.00
grp_b
row_5 2 5,550.00 NA 2 $1,325.81
row_6 NA fig $13.26
row_7 2 777,000.00 grapefruit NA
row_8 2 8,880,000.00 honeydew $0.44
1 Alphabetical fruit.
2 Using commas for separators.

Modify the table’s background color (with table.background.color) to be "lightcyan".

tab_1 |>
  tab_options(table.background.color = "lightcyan")
Data listing from exibble
exibble is an R dataset
num char1 currency
grp_a
row_1 0.11 apricot $49.95
row_2 2.22 banana $17.95
row_3 33.33 coconut $1.39
row_4 444.40 durian 2 $65,100.00
grp_b
row_5 2 5,550.00 NA 2 $1,325.81
row_6 NA fig $13.26
row_7 2 777,000.00 grapefruit NA
row_8 2 8,880,000.00 honeydew $0.44
1 Alphabetical fruit.
2 Using commas for separators.

Use letters as the glyphs for footnote references (with footnotes.marks and the letters vector).

tab_1 |>
  tab_options(footnotes.marks = letters)
Data listing from exibble
exibble is an R dataset
num chara currency
grp_a
row_1 0.11 apricot $49.95
row_2 2.22 banana $17.95
row_3 33.33 coconut $1.39
row_4 444.40 durian b $65,100.00
grp_b
row_5 b 5,550.00 NA b $1,325.81
row_6 NA fig $13.26
row_7 b 777,000.00 grapefruit NA
row_8 b 8,880,000.00 honeydew $0.44
a Alphabetical fruit.
b Using commas for separators.

Change the padding of data rows to 5px with data_row.padding.

tab_1 |> 
  tab_options(data_row.padding = px(5)) # px() helper function used here
Data listing from exibble
exibble is an R dataset
num char1 currency
grp_a
row_1 0.11 apricot $49.95
row_2 2.22 banana $17.95
row_3 33.33 coconut $1.39
row_4 444.40 durian 2 $65,100.00
grp_b
row_5 2 5,550.00 NA 2 $1,325.81
row_6 NA fig $13.26
row_7 2 777,000.00 grapefruit NA
row_8 2 8,880,000.00 honeydew $0.44
1 Alphabetical fruit.
2 Using commas for separators.

Reduce the size of the title and the subtitle text (with heading.title.font.size and heading.subtitle.font.size).

tab_1 |>
  tab_options(
    heading.title.font.size = "small",
    heading.subtitle.font.size = "small"
  )
Data listing from exibble
exibble is an R dataset
num char1 currency
grp_a
row_1 0.11 apricot $49.95
row_2 2.22 banana $17.95
row_3 33.33 coconut $1.39
row_4 444.40 durian 2 $65,100.00
grp_b
row_5 2 5,550.00 NA 2 $1,325.81
row_6 NA fig $13.26
row_7 2 777,000.00 grapefruit NA
row_8 2 8,880,000.00 honeydew $0.44
1 Alphabetical fruit.
2 Using commas for separators.

SUMMARY

  1. A header can be added to a gt table with tab_header(); use md() to style title/subtitle.
  2. Source notes can be added to the footer of a table with tab_source_note().
  3. Spanner column labels can be placed above selected column labels with tab_spanner().
  4. If you have a stub and want a label above it, use tab_stubhead().
  5. Footnotes can be placed in specific cells (with help from the cells_*() functions) using tab_footnote().
  6. The tab_style() function helps to style specified cells; use both the cells_*() and cell_*() functions for targeting and style specification.
  7. Tons of options that affect the entire table (i.e., not targeted) can be used with tab_options().